home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / c / pmm / doku / libdoku / supra.doc < prev    next >
Text File  |  1999-06-14  |  25KB  |  739 lines
  1. TABLE OF CONTENTS
  2.  
  3. AddToolType
  4. FCopy
  5. FileType
  6. FreeNewImg
  7. MakeNewImg
  8. MakePath
  9. ObtPens
  10. RecDirFree
  11. RecDirInit
  12. RecDirNext
  13. RecDirTags
  14. RelPens
  15. AddToolType                                                       AddToolType
  16.  
  17.    NAME
  18.        AddToolType -- Adds or changes a new/existing icon's tooltype (V10)
  19.        (icon)
  20.  
  21.    SYNOPSIS
  22.        tool = AddToolType(diskobj, tooltype)
  23.  
  24.        char * = AddToolType(struct DiskObject *, char *);
  25.  
  26.    FUNCTION
  27.        This function lets you add a new tooltype to a disk object's
  28.        tooltype list, or change already existing one.
  29.        It is a smart routine that makes dealing with tooltypes very
  30.        straightforward.
  31.  
  32.        The following is an example table about how a tooltype list gets
  33.        changed based on a provided tool:
  34.  
  35.         existing tooltype | provided tooltype | result
  36.        ----------------------------------------------------------
  37.             NOGUI         |     (NOGUI)       | (NOGUI)
  38.             (NOGUI)       |     NOGUI         | NOGUI
  39.             NOGUI         |     NOGUI         | NOGUI
  40.             SIZE=10       |     SIZE=15       | SIZE=15
  41.             (SIZE=10)     |     SIZE=15       | SIZE=15
  42.             SIZE=10       |     (SIZE=15)     | (SIZE=15)
  43.             [a new one]   |     DONOTWAIT     | DONOTWAIT [added to a list]
  44.  
  45.  
  46.    INPUTS
  47.        diskobj - points to an allocated DiskObject structure (usually
  48.                  created by GetDiskObject() function).
  49.  
  50.        tooltype - points to a new tooltype string to be added to a
  51.                   provided tooltype list
  52.  
  53.    RESULT
  54.        tool = pointer to a provided tooltype string if succeeds, otherwise
  55.        NULL.
  56.  
  57.    EXAMPLES
  58.        This example opens a ram:test.info icon and asks a user to enter
  59.        tooltypes to be added (until user enters 'end').
  60.  
  61.  
  62.    #include <libraries/supra.h>
  63.    #include <clib/exec_protos.h>
  64.    #include <clib/dos_protos.h>
  65.    #include <clib/icon_protos.h>
  66.    #include <stdio.h>
  67.    #include <string.h>
  68.  
  69.    #define filename "ram:test"
  70.  
  71.    struct Library *IconBase = NULL;
  72.  
  73.    struct DiskObject *diskobj;
  74.  
  75.    char icon[50];
  76.  
  77.    main()
  78.    {
  79.        key = NULL;
  80.            if (IntuitionBase = OpenLibrary("intuition.library",0)) {
  81.                if (IconBase = OpenLibrary("icon.library",0)) {
  82.                    if (diskobj = GetDiskObject(filename)) {
  83.                        do {
  84.                            gets(icon);
  85.                            if (strcmp(icon, "end") == 0) break;
  86.                            AddToolType(diskobj, icon);
  87.                        } while (TRUE);
  88.  
  89.                        PutDiskObject(filename, diskobj);
  90.                        FreeDiskObject(diskobj);
  91.                        FreeRemember(&key, TRUE);
  92.                    }
  93.                }
  94.            }
  95.  
  96.        if (IconBase) CloseLibrary(IconBase);
  97.        if (IntuitionBase) CloseLibrary(IntuitionBase);
  98.    }
  99.  
  100.  
  101.    NOTES
  102.        All memory allocations used by AddToolType() will be stored in
  103.        FreeList structure that MUST be allocated right after the provided
  104.        DiskObject structure. If you called your DiskObject by GetDiskObject()
  105.        or GetDiskObjectNew() then FreeList is automaticly appended.
  106.        All allocated memory is freed when you call FreeDiskObject().
  107.  
  108.        This function requires icon.library to be opened.
  109.  
  110.  
  111.  
  112. FCopy                                                                   FCopy
  113.  
  114.    NAME
  115.        FCopy -- copies source file to destination file (V10)
  116.        (dos V36)
  117.  
  118.    SYNOPSIS
  119.        error = FCopy(source, dest, buffer)
  120.  
  121.        UBYTE = FCopy(char *, char *, LONG);
  122.  
  123.    FUNCTION
  124.        This function works very similar to C:Copy program. It copies
  125.        a source file to a destination file.
  126.  
  127.    INPUTS
  128.        source - pointer to a source file name (with a relative or
  129.                 absolute path)
  130.        dest - pointer to a destination file name
  131.        buffer - maximum size of a buffer (in bytes) to be
  132.                 allocated for copying. If this buffer is 0, FCopy()
  133.                 will try to allocate buffer a size of a source file,
  134.                 or the largest memory block available. (this is the
  135.                 fastest way).
  136.  
  137.    RESULT
  138.        error - zero if no error. Function may return one of the
  139.        following error definitions:
  140.  
  141.            FC_ERR_EXIST - Source file does not exist
  142.            FC_ERR_EXAM  - Error during examination of a source file
  143.            FC_ERR_MEM   - Not enough memory availabe
  144.            FC_ERR_OPEN  - Source file could not be oppened
  145.            FC_ERR_READ  - Error while reading a source file
  146.            FC_ERR_DIR   - Source file path is a directory
  147.            FC_ERR_DEST  - Destination file could not be created
  148.            FC_ERR_WRITE - Error while writing to a destination file
  149.  
  150.    EXAMPLE
  151.  
  152.        /* This example will copy a file c:dir to ram: with a new name
  153.         * list.
  154.         */
  155.  
  156.        UBYTE err;
  157.  
  158.        if ((err = FCopy("C:Dir", "ram:list", 0)) == 0) {
  159.  
  160.            no errors...
  161.  
  162.        } else {
  163.            printf("Error: %d\n", err); /* Error occured during FCopy() */
  164.  
  165.        }
  166.  
  167.    NOTES
  168.        If an error occurs then a destination file will not be deleted
  169.        if it has already been partly copied.
  170.  
  171. FileType                                                             FileType
  172.  
  173.    NAME
  174.        FileType -- Examines if a file is a directory or a file (V10)
  175.  
  176.    SYNOPSIS
  177.        type = FileType(filename)
  178.  
  179.        LONG = FileType(char *);
  180.  
  181.    FUNCTION
  182.        Will use dos.library's Examine() function to determine
  183.        whether a specified file(path) exists, and if it is a file
  184.        or a directory.
  185.  
  186.    INPUTS
  187.        filename - pointer to a filename string
  188.  
  189.    RESULT
  190.        returns 0 if specified file/path does not exist. If < 0, then
  191.        it is a plain file. If > 0 a directory.
  192.        This function actually returns fib_DirEntryType (from
  193.        struct FileInfoBlock).
  194.  
  195.    EXAMPLE
  196.  
  197.        type = FileType("SYS:System");
  198.  
  199.        type will be > 0, which means that "SYS:System" is a dir.
  200.  
  201. FreeNewImg                                                         FreeNewImg
  202.  
  203.    NAME
  204.        FreeNewImg -- frees memory allocated by MakeNewImg() (V10)
  205.  
  206.    SYNOPSIS
  207.        FreeNewImg(newImage)
  208.  
  209.        void FreeNewImg(struct Image *);
  210.  
  211.    FUNCTION
  212.        You must free a new created image with this function, when
  213.        it is no longer needed.
  214.  
  215.    SEE ALSO
  216.        MakeNewImg()
  217.  
  218. MakeNewImg                                                         MakeNewImg
  219.  
  220.    NAME
  221.        MakeNewImg -- Remap an image to any new colours (V10)
  222.  
  223.    SYNOPSIS
  224.        newImage = MakeNewImg(oldImage, palette)
  225.  
  226.        struct Image * = MakeNewImg(struct Image *, ULONG *);
  227.  
  228.    FUNCTION
  229.        This function creates a new clone image of a provided
  230.        image, and it remaps the new image according to a provided
  231.        pen colour list.
  232.        This is very useful when you need your image to use
  233.        specific colours anywhere in the available palette.
  234.        (e.g. you obtained some free pens from a palette, and
  235.        you want your image to be shown with those pens).
  236.        It is possible to modify an image's pens with PlanePick and
  237.        PlaneOnOff fields (see Image structure), but this has a major
  238.        limitation: most colour combinations are not possible to get.
  239.  
  240.        If your image has four colours (0,1,2,3), and you want to
  241.        remap these to (0,16,4,7), you simply call this function,
  242.        providing it with the image and a new colour map, and a
  243.        new image will be created for you.
  244.  
  245.    INPUTS
  246.        oldImage - pointer to an Image structure to be remapped
  247.        palette  - pointer to a list of new pens
  248.  
  249.        A pens list should contain the exact number of pens as
  250.        an old image uses. (2 if image's depth is 1, 4 if image's
  251.        depth is 2, etc.). An image's colour 0 will be remapped to the
  252.        first pen on the list, image's colour 1 will be remapped to
  253.        the second pen on the list and so on.
  254.  
  255.    RESULT
  256.        newImage - pointer to a newly initialized remapped old image's
  257.                   clone. If there is not enough memory, newImage will
  258.                   be NULL.
  259.        IMPORTANT: If a new image was created you have to call
  260.        FreeNewImg() to free the allocated memory, when you no longer
  261.        need to use it!
  262.  
  263.    EXAMPLE
  264.  
  265.        We have a depth 2 image (4 colours), and we want to use pens
  266.        0,16,4,7 instead of 0,1,2,3:
  267.  
  268.  
  269.        struct Image OldImage = {
  270.            ....    /* This is a data of our original image */
  271.  
  272.        struct Image *NewImage;
  273.        ULONG pal[] = {0, 16, 4, 7}; /* The new pen list */
  274.  
  275.        if (NewImage = MakeNewImg(&OldImage, &pal[0])) {
  276.           DrawImage(rp, NewImage);
  277.           FreeNewImg(NewImage);    /* We will no longer use it */
  278.        }
  279.  
  280.    NOTE
  281.        A new image's depth will change to a depth that can hold
  282.        the largest pen number from a pens list. It does not have
  283.        any smart routine to check if the depth can be optimized
  284.        down, by altering PlanePick and PlaneOnOff, yet.
  285.        Bear in mind that if you provide a pen 255, then a new image's
  286.        depth will be at least 8.
  287.  
  288.        You MUST free a new image with FreeNewImg() when it's no longer
  289.        needed!
  290.  
  291.        This function can take much time when remapping larger images
  292.        with more depths.
  293.  
  294.    BUGS
  295.        None found.
  296.  
  297.    SEE ALSO
  298.        FreeNewImg()
  299.  
  300. MakePath                                                             MakePath
  301.  
  302.    NAME
  303.        MakePath -- Creates all new directories in a path (V10)
  304.  
  305.    SYNOPSIS
  306.        suc = MakePath(path)
  307.  
  308.        BOOL = MakePath(char *);
  309.  
  310.    FUNCTION
  311.        This function creates a whole specified path of directories.
  312.        It works similar to CreateDir() except that it can create
  313.        more subdirs at once. User does not have to care if all
  314.        sub dirs in a specified path already exist or not.
  315.  
  316.    INPUTS
  317.        path - pointer to a path string to create. A path can be
  318.        relative to a current dir or absolute.
  319.  
  320.    RESULT
  321.        suc - TRUE if succeeds (path was created). FALSE if a path
  322.        could not be created.
  323.  
  324.    EXAMPLE
  325.  
  326.        suc = MakePath("RAM:way/to/many/dirs");
  327.  
  328.        The above function will try to make all non-existing dirs
  329.        in a path RAM:way/to/many/dirs.
  330.  
  331.    SEE ALSO
  332.        CreateDir()
  333.  
  334. ObtPens                                                               ObtPens
  335.  
  336.    NAME
  337.        ObtPens -- Obtain best pens from a list of colors (V10)
  338.        (gfx V39)
  339.  
  340.    SYNOPSIS
  341.        number = ObtPens(cm, PalTable, PensTable, TagItem)
  342.  
  343.        ULONG  = ObtPens(struct ColorMap *, ULONG *, ULONG *,
  344.                  struct TagItem *);
  345.  
  346.    FUNCTION
  347.        This function calls ObtainBestPen() on a list of color
  348.        entries, and puts results into a new pens list.
  349.  
  350.        It will attempt to find colors in your viewport closest to
  351.        the provided colors list (PalTable).
  352.        This is usefull when you want to use an image with more
  353.        specific colors on a public screen with a sharable palette.
  354.  
  355.    INPUTS
  356.        cm = colormap
  357.        PalTable - list of RGB entries for each color you want to use.
  358.                   The format of this table is the same as for LoadRGB32():
  359.  
  360.              1 Word with the number of colors to obtain
  361.              1 Word with the first color to be obtained
  362.              3 longwords representing a left justified 32 bit RGB triplet
  363.              The list is terminated by a count value of 0.
  364.  
  365.              examples:
  366.                ULONG PalTable[]={2l<<16+1,0,0,0, 0xffffffff,0,0, 0};
  367.                    two entries (black, red); obtains only red one
  368.  
  369.        PensTable - list of pen numbers on your viewport, obtained by
  370.                    this function. First entry in PensTable will represent
  371.                    the first color in PalTable, and so on.
  372.                    NOTE that entries in PensTable with count number lower
  373.                    than the first color to be obtained (provided in
  374.                    PalTable) will be unaffected!
  375.  
  376.        TagItem - this tagitem will be passed to ObtainBestPen() function,
  377.                  that is called within ObtPens(). Please see ObtainBestPen()
  378.                  in order to decide what kind of precision for obtaining
  379.                  colors you will need. If this is NULL, PRECISION_IMAGE will
  380.                  be used.
  381.  
  382.    RESULT
  383.        number = number of obtained colours (always the same as the first
  384.        Word in PalTable), or 0 if failed. If it succeeds you must call
  385.        RelPens() to free obtained colors.
  386.  
  387.  
  388.    EXAMPLES
  389.  
  390.        The following example will obtain red, green and blue colours in a
  391.        viewport, and will put obtained pens into pens[] table. pens[0] will
  392.        be untouched (will remain the same colour as viewport's background).
  393.  
  394.        ULONG pal[((4<<16)+1, /* 4 entries, starting with the second one */
  395.                    0, 0, 0,          /* black - will ignore this one */
  396.                    0xffffffff, 0, 0, /* red */
  397.                    0, 0xffffffff, 0, /* green */
  398.                    0, 0, 0xffffffff, /* blue */
  399.                    0};
  400.  
  401.        ULONG pens[4];
  402.  
  403.        ObtPens(cm, pal, pens, NULL);
  404.  
  405.        SetAPen(rp, pens[1]);   /* Set the primary pen to red */
  406.        Text(rp, "I'm red!", 8);
  407.  
  408.  
  409.    NOTES
  410.        You MUST call RelPens() to free all obtained colors if ObtPens()
  411.        have succeeded, but you must not call it if ObtPens() returns 0.
  412.        You MUST open graphics library (V39 or higher) before calling this
  413.        function.
  414.  
  415.    SEE ALSO
  416.        RelPens(), ObtainBestPen(), LoadRGB32()
  417.  
  418. RecDirFree                                                         RecDirFree
  419.  
  420.    NAME
  421.        RecDirFree -- Unlocks all locked paths (V10)
  422.        (dos V36)
  423.  
  424.    SYNOPSIS
  425.        void RecDirFree(RecDirInfo)
  426.  
  427.        void RecDirFree(struct RecDirInfo *);
  428.  
  429.    FUNCTION
  430.        This function is called internally when error occurs in
  431.        RecDirNext(), so you don't have to call it then!
  432.        You can only call it when you no longer want to use RecDirNext(),
  433.        before it finishes the scanning process.
  434.        You DO NOT have to call RecDirFree() when you get any error,
  435.        even DN_ERR_END (scanning process complete)!
  436.  
  437.    INPUTS
  438.        RecDirInfo - pointer to struct RecDirInfo which has been
  439.                     called with RecDirInit()
  440.  
  441.    RESULT
  442.        none
  443.  
  444.    SEE ALSO
  445.        RecDirInit(), RecDirNext(), RecDirNextTagList()
  446.  
  447. RecDirInit                                                         RecDirInit
  448.  
  449.    NAME
  450.        RecDirInit -- Initializes recursive files scanning process (V10)
  451.        (dos V36)
  452.  
  453.    SYNOPSIS
  454.        error = RecDirInit(RecDirInfo)
  455.  
  456.        UBYTE = RecDirInit(struct RecDirInfo *)
  457.  
  458.    FUNCTION
  459.        This function is required to start scanning files through entire
  460.        or partial directory tree. It locks a directory path provided in
  461.        RecDirInfo structure, then files can be examined by calling
  462.        RecDirNext() function. Please see RecDirNext() for more
  463.        explanation on how this is useful.
  464.        You should initialize RecDirInfo by yourself, and you MUST set
  465.        rdi_Path, rdi_Num, and rdi_Pattern.
  466.  
  467.    INPUTS
  468.        RecDirInfo - pointer to RecDirInfo structure, which should be
  469.        allocated and initialized before RecDirInit() is called.
  470.        You must set its rdi_Path field to starting directory path
  471.        you want to scan.
  472.        
  473.        Set rdi_Num for maximum number of directories you wish to scan
  474.        into. If you set rdi_Num to 1 it will only scan one level (that
  475.        rdi_Path points to). If you set rdi_Num to -1 it will scan
  476.        unlimited number of subdirectories deep.
  477.  
  478.        If rdi_Pattern field is non-NULL and points to a string then
  479.        calling RecDirNext will only return files that match the
  480.        pattern string. NOTE that rdi_Pattern should point to a string
  481.        which has been parsed with ParsePattern().
  482.  
  483.    RESULT
  484.        error - 0 if no error, otherwise returns one of the following
  485.        errors (also see libraries/supra.h):
  486.            RDI_ERR_FILE - Path provided in rdi_Path points to a file
  487.                           not directory.
  488.            RDI_ERR_NONEXIST - Path provided in rdi_Path does not exist.
  489.            RDI_ERR_MEM - not enough memory to execute RecDirInit().
  490.  
  491.    EXAMPLE
  492.        Please see an example in RecDirNext() function.
  493.  
  494.    NOTES
  495.        IMPORTANT: You MUST open dos.library before calling RecDirInit()!
  496.        rdi_Path is a path relative to a current path your program uses.
  497.        That means you can set rdi_Path to "" to scan from current
  498.        directory, or "/" to scan parent directory.
  499.  
  500.    BUGS
  501.        None found yet.
  502.  
  503.    SEE ALSO
  504.        RecDirFree(), RecDirNext(), libraries/supra.h
  505.  
  506. RecDirNext                                                         RecDirNext
  507.  
  508.    NAME
  509.        RecDirNext -- Gets information about the next file (V10)
  510.        (dos V36)
  511.  
  512.    SYNOPSIS
  513.        error = RecDirNext(RecDirInfo, RecDirFIB);
  514.  
  515.        UBYTE = RecDirNext(struct RecDirInfo *, struct RecDirFIB *);
  516.  
  517.    FUNCTION
  518.        Retrieves information about the next file in a scanning process.
  519.        Calling this function  will not provide a list of sorted files
  520.        niether by ASCII order nor by directory levels. That means
  521.        it will scan files as they have been stored on a disk drive.
  522.  
  523.        The main advantage of using this function from using ExNext()
  524.        is that you don't have to program a recursive scanning routine
  525.        by yourself. You need only to provide lowest directory path,
  526.        how deep into subdirectories you want to scan, and which
  527.        information about files you need to be provided with.
  528.        RecDirNext() will only return files but no directories.
  529.        You are also able to select a matching pattern so that only
  530.        files which match it will be returned.
  531.  
  532.        Please see RecDirInit() for more info.
  533.  
  534.    INPUTS
  535.        RecDirInfo - pointer to RecDirInfo structure. You MUST call
  536.        RecDirInit(), providing it with this structure, before calling
  537.        any RecDirNext() function.
  538.  
  539.        RecDirFIB - pointer to RecDirFIB structure which should be
  540.        previousely allocated. You only set those fields in the
  541.        structure that you want to have information about. Any field
  542.        should point to a variable into which information will be stored.
  543.        Check "struct RecDirFIB" to see what each field mean.
  544.        All field in RecDirFIB structure that are set to NULL will be
  545.        ignored.
  546.  
  547.    RESULT
  548.        error - zero if no error. Otherwise one of the following:
  549.            DN_ERR_END - scanning is completed. You should not call
  550.                         any RecDirNext() again.
  551.            DN_ERR_EXAMINE - Failure while examining a file.
  552.            DN_ERR_MEM - not enough memory available to complete
  553.                         the operation.
  554.            IF any error will be resulted, RecDirFree will be called
  555.            internally.
  556.  
  557.  
  558.    EXAMPLE
  559.        This example will scan through the entire HD0: disk device, and
  560.        will print for each file: its dir path, its name, its size.
  561.  
  562.  
  563.    #include <stdio.h>
  564.    #include <stdlib.h>
  565.    #include <clib/exec_protos.h>
  566.    #include <clib/dos_protos.h>
  567.    #include <libraries/supra.h>
  568.  
  569.    struct RecDirFIB rdf;
  570.    struct RecDirInfo rdi;
  571.    char name[30];
  572.    char path[100];
  573.    LONG size;
  574.    LONG err;
  575.  
  576.    struct DosBase *DosBase;
  577.  
  578.    void main()
  579.    {
  580.         if (DosBase = (struct DosBase *)OpenLibrary("dos.library",0)) {
  581.  
  582.            rdi.rdi_Path = "RAM:";  /* from path "RAM:" */
  583.            rdi.rdi_Num = -1;       /* Unlimited subdirs deep */
  584.            rdi.rdi_Pattern = NULL; /* Don't match files for pattern */
  585.  
  586.            if (RecDirInit(&rdi) == 0) {
  587.                rdf.Path = path;  /* We want to get files' path, name and size
  588.  */
  589.                rdf.Name = name;
  590.                rdf.Size = &size;
  591.                while ((err = RecDirNext(&rdi, &rdf)) == 0) {
  592.                    printf("%s (%s) %ld\n", path, name, size);
  593.                }
  594.  
  595.                /* Now check if DN_ERR_END or some other unexpected error */
  596.                switch (err) {
  597.                    case DN_ERR_END:
  598.                        printf("Scanning completed\n");
  599.                        break;
  600.                    case DN_ERR_EXAMINE:
  601.                        printf("Error: trouble examining a file\n");
  602.                        break;
  603.                    case DN_ERR_MEM:
  604.                        printf("Error: not enough memory\n");
  605.                }
  606.            }
  607.  
  608.            CloseLibrary((struct Library *)DosBase);
  609.        } else printf("Cannot open dos.library\n");
  610.    }
  611.  
  612.  
  613.    NOTES
  614.        If you want to end scanning earlier you have to call RecDirFree()!
  615.  
  616.    BUGS
  617.        none found
  618.  
  619.    SEE ALSO
  620.        RecDirInit(), RecDirTags(), RecDirFree(), libraries/supra.h
  621.  
  622. RecDirTags                                                         RecDirTags
  623.  
  624.    NAME
  625.        RecDirNextTagList -- Gets information about next file (V10)
  626.        (dos V36)
  627.  
  628.    SYNOPSIS
  629.        error = RecDirNextTagList(RecDirInfo, RecDirFIB, TagItems)
  630.  
  631.        UBYTE = RecDirNextTagList(struct RecDirInfo *, struct RecDirFIB *,
  632.                    struct TagItem *);
  633.  
  634.  
  635.        error = RecDirNextTags(RecDirInfo, RecDirFIB, tag1, ...)
  636.  
  637.        UBYTE = RecDirNextTags(struct RecDirInfo *, struct RecDirFIB *,
  638.                    ULONG tag1, ...);*
  639.  
  640.  
  641.    FUNCTION
  642.        This function does the same as RecDirNext() but it provides
  643.        a TagList extension. Any additional tags will override initial
  644.        settings in RecDirFIB structure.
  645.  
  646.    INPUTS
  647.        RecDirInfo - pointer to RecDirInfo structure which has been
  648.                     called with RecDirInit()
  649.        RecDirFIB  - pointer to initialized and set RecDirFIB structure,
  650.                     or NULL.
  651.                     You can get files' information either by setting
  652.                     variables to this structure before calling
  653.                     RecDirNextTagList(), or by providing TagItems you
  654.                     want. 
  655.                     NOTE: If you provide any TagItem then RecDirFIB will
  656.                     be changed (if it's non-NULL)!
  657.  
  658.        Tags - The following tags are available:
  659.  
  660.            RD_NAME - File name will be provided. ti_Data should carry
  661.                      a pointer to a string buffer (char *)
  662.            RD_PATH - Directory path where scanned file is.
  663.            RD_FULL - Full directory path + file name
  664.            RD_SIZE - File lenght in bytes. ti_Data must have a pointer to
  665.                      a LONG number (LONG *).
  666.            RD_FLAGS - File's protection flags. ti_Data must have a pointer
  667.                      to LONG.
  668.            RD_COMMENT - File's comment note. ti_Data carries a pointer to
  669.                      a string buffer.
  670.            RD_DATE - File's DateStamp structure. Function will copy the
  671.                      entire DateStamp structure into struct DateStamp
  672.                      provided in ti_Data field that points to it.
  673.            RD_BLOCKS - File size in blocks. ti_Data should have a pointer
  674.                        to LONG
  675.            RD_UID - Owner's UID (not supported with all file systems).
  676.                     ti_Data should have a pointer to UWORD variable.
  677.            RD_GID - Owner's GID. ti_Data has a pointer to UWORD variable.
  678.            RD_FIB - FileInfoBlock. Function will copy examined file's
  679.                     FileInfoBlock to a provided struct FileInfoBlock
  680.                     via ti_Data (ti_Data has a pointer to an allocated
  681.                     FileInfoBlock structure).
  682.  
  683.    RESULT
  684.        Same as for RecDirNext()
  685.  
  686.    EXAMPLE
  687.  
  688.        See an example for RecDirNext(). You can replace its line
  689.  
  690.        RecDirNext(&rdi, &rdf);
  691.           *with*
  692.        RecDirNextTags(&rdi, NULL, RD_PATH, path,
  693.                                   RD_NAME, name,
  694.                                   RD_SIZE, &size,
  695.                                   TAG_DONE);
  696.    NOTES
  697.        If RecDirFIB is not NULL, and you provide some tags as well then
  698.        RecDirFIB will be changed. This may change in the future so
  699.        that provided RecDirFIB will not change.
  700.  
  701.    BUGS
  702.        none found
  703.  
  704.    SEE ALSO
  705.        RecDirNext(), RecDirInit(), libraries/supra.h
  706.  
  707. RelPens                                                               RelPens
  708.  
  709.    NAME
  710.        RelPens -- Release a list of pens obtained by ObtPens (V10)
  711.        (gfx V39)
  712.    SYNOPSIS
  713.        RelPens(cm, PalTable, PensTable)
  714.  
  715.        void (struct ColorMap *, ULONG *, ULONG *);
  716.  
  717.    FUNCTION
  718.        This function repeats calls to ReleasePen() in order to
  719.        release all pens obtained by ObtPens().
  720.  
  721.    INPUTS
  722.        cm = colormap
  723.        PalTable - the same PalTable called with ObtPens()
  724.        PensTable - the same PensTable called with ObtPens()
  725.  
  726.    NOTES
  727.        Please DO NOT modify PalTable and PensTable between calling
  728.        ObtPens() and RelPens(). This function uses the first long
  729.        word from PalTable (describing number of entries and starting
  730.        position), and all entries from PensTable (except those entries
  731.        that are lower than a starting position).
  732.        You MUST open graphics library (V39 or higher) before calling
  733.        this function!
  734.  
  735.    SEE ALSO
  736.        ObtPens(), ReleasePen()
  737.  
  738.  
  739.